1.Обзор системы | 2. Мой первый проект | 3. Модель | 4. Формы @View | 5. Списки @Tab | 6. Объектно-реляционное связывание | 7. Контроллеры | 8. Приложение | 9. Расширенные возможности

Глава 8: Приложение (Application)

Приложение - это комплект программного обеспечения, готовый к использованию конечным пользователем. В предыдущих главах вы получили информацию о том, как создавать кирпичики (компоненты, действия и т.д.), из которых состоит приложения OX. Теперь у вас будет возможность изучить, как из этих кирпичков построить готовое приложение OX.
Определение приложения OpenXava дается в файле application.xml, который находится в папке xava вашего проекта OX.
Синтаксис файла таков:

 <application
 name="name" <!-- 1 -->
 label="label" <!-- 2 -->
 >
 <default-module ... /> ... <!-- 3 New in v2.2.2 -->
 <module ... /> ... <!-- 4 -->
 </application>

1. name (обязательно): Имя приложения.
2. label (опционально): Вместо данного поля рекомендуется использовать файлы i18n (см. Интернационализация приложения).
3. default-module (одно вхождение, опционально): (Начиная с версии v2.2.2) Определение контроллеров для предопределенных по-умолчанию модулей (автоматически генерируются для каждого компонента).
4. module (несколько вхождений, опционально): Определяется каждый модуль, доступный к использованию конечным пользователем.

Вкратце, приложение OX - это есть набор модулей. Давайте посмотрим на определение модуля:

 <module
 name="name" <!-- 1 -->
 folder="folder" <!-- 2 -->
 label="label" <!-- 3 -->
 description="description" <!-- 4 -->
 >
 <env-var ... /> ... <!-- 5 -->
 <model ... /> <!-- 6 -->
 <view ... /> <!-- 7 -->
 <web-view ... /> <!-- 8 -->
 <tab ... /> <!-- 9 -->
 <controller ... /> ... <!-- 10 -->
 <mode-controller ... /> <!-- 11 -->
 <doc ... /> <!-- 12 -->
 </module>

1. name (обязательный элемент): Уникальный идентификатор модуля приложения.
2. folder (необязательный элемент): Папка, в которой будет находиться модуль. В настоящее время параметр folder используется только для создания струкуры папок в JetSpeed2, но в будущем возможно более широкое использование. Пока же, данный параметр может помочь классифицировать модули. Например, можно использовать вложение папок ("invoicing/reports" или "invoicing.reports").
3. label (необязательный элемент): Краткое название, которое будет отображено пользователю. Вместо данного параметра мы рекомендуем использовать файлы i18n.
4. description (необязательный элемент): Подробное описание, которое будет отображено пользователю. Вместо данного параметра мы рекомендуем использовать i18n.
5. env-var (несколько вхождений, необязательный элемент): Позволяет вам определить переменные, значения которых будут доступны действия (actions) OX. Таким образом, вы можете определить действия для модуля.
6. model (необязательный элемент): Имя компонента для использования в моделе. Если значение данного элемента путое, то необходимо указать значение для элемента web-view.
7. view (необязательный элемент): Представление-Форма, которое будет использовано для данного модуля. Если элемент не заполнен, используется стандартное представление..
8. web-view (необязательный элемент): Элемент предназначен для указания страницы JSP, используемой вместо представления.
9. tab (необязательный элементl): Имя табличного представления, которое будет задействовано для данного модуля. Если элемент не определение, используется стандартное табличное представление.
10. controller (несколько вхождений, необязательный элемент): Контроллеры для доступных действий, используемые изначально.
11. mode-controller (необязательный элемент): Позволяет определить поведение для переключения между представлением-формой и представлением-списком (табличное представление). Также позволяет определить модуль без представления или представлений.
12. doc (необязательный элемент): Позволяет определить модуль, который содержит только статические страницы (документацию). Данный элемент является взаимоисключающим по отношению к другим элементам. Данный элемент удобно использовать для генерации информационных портлетов вашего приложения.

Пример типового модуля

Определение простейшего модуля выглядит так:

 <application name="Management">
 <module name="Warehouse" folder="warehousing">
 <model name="Warehouse"/>
 <controller name="Typical"/>
 <controller name="Warehouse"/>
 </module>
 ...
 </application>

В этом примере мы создали модуль, который предоставляет пользователю следующие функциональные возможности: создание, удаление, изменение и поиск записей для модели Warehouse, создание отчетов в формате PDF и экспортирование данных в таблицы Excel из модели(благодаря контроллеру Typical), а также наш модуль позволяет выполнять действия, реализованные только для warehouses (благодаря контроллеру Warehouse). В случае использования JetSpeed2э наш модуль будет размещен в папке "warehousing".
Чтобы запустить данный модуль, вам неободимо открыть веб броузер и перейти на страницу::
http://localhost:8080/Management/xava/module.jsp?application=Management&module=Warehouse
Портлет, формируемый OX, позволяет использовать ваш модуль в порталах Java, поддерживающих портлеты, совместимые со спецификацией JSR-168.

Предопределенные по-умолчанию модули (начиная с версии v2.2.2)

Не обязательно указывать все модули в applicaction.xml, т.к. OpenXava предполагает, что для каждого компонента приложения существует соответствующий модуль, предопределённый по-умолчанию.
То есть, если вы определи компонент Invoice.xml, то вы сразу можете зайти по адресу:
http://localhost:8080/Management/xava/module.jsp?application=Management&module=Invoice
Также сгенерированный портлет позволяет вам устанавливать модуль как портлет JSR-168.
И все это без внесения изменений в application.xml.
Контроллер для неявных модулей по-умолчанию будет Typical. Но такое поведение системы можно переопределить, задав элемент default-module в файле application.xml, следующим образом:

 <application name="Management">
 
 <default-module>
 <controller name="ManagementCRUD"/>
 </default-module>
 
 </application>

В этом примере все модули приложения Management будут иметь контроллер ManagementCRUD.
Если вы хотите, чтобы конкрентный модуль не использовал дефолтные контроллеры, то у вас две возможности:

1. Определить контроллер в файле controllers.xml с таким же именем, как имеет ваш компонент.
2. Определить модуль в application.xml, как было описано выше.

Суммируя, если вы определили компонент, назовём его Customer, затем вам необходимо определить модуль Customer, а также портлет. Модуль может быть определен одим из следующих способов:

1. Если определить модуль Customer в файле application.xml, то будет использоваться данный модуль. Иначе...
2. Если определить контроллер Customer в файле controllers.xml, то модуль будет автоматически сгенерирован с использованием Customer как контроллера и Customer как модели. Иначе..
3. Если определить элмент default-module в файлу application.xml, то автоматически генерируемый модуль будет использовать контроллеры, определенные в элементе default-module, а компонент Customer будет использован как модель. Иначе...
4. Если ничего другого не определено, то как последнаяя соломенка применяется контроллер Typical и модель Customer, как модель которая подразумевается

Модуль только с видом @View

Модуль, поддерживающий только представление в виде формы с полями, отображающее только одну запись одновременно, определяется так:

 <module name="InvoiceNoList">
 <model name="Invoice"/>
 <controller name="Typical"/>
 <mode-controller name="Void"/> <!-- 1 -->
 </module>

Контроллер изменения режима представления Void (1) удаляет ссылку на переключение "detail – list". В таком случае используется режим просмотра по-умолчания, коим является режим Detail (Определяется с помощью аннотации @View).

Модуль только с видом @Tab

Модуль, поддерживающий только табличное представление, определяется так:

 <module name="FamilyListOnly">
 <env-var name="XAVA_LIST_ACTION" value=""/> <!-- 1 New in v2.0.4 -->
 <model name="Family"/>
 <controller name="Typical"/>
 <controller name="ListOnly"/> <!-- 2 -->
 <mode-controller name="Void"/> <!-- 3 -->
 </module>

Котроллер изменения режима представления Void (3) удаляет ссылку на переключение "detail – list". Определение контроллера ListOnly (2) заставляет OX использовать табличное представление. Завершающим штрихом является присвоение пустой строки переменной XAVA_LIST_ACTION (1), что приводит к тому, что ссылка на представление-форму в каждой строке списка записей, будет пустой (начиная с версии v2.0.4).

Модуль для документации

Модуль документации предназначен для предостваление документации HTML. Ниже дано определение модуля:

 <module name="Description">
 <doc url="doc/description" languages="en,ru"/>
 </module>

Данный модуль показывает один из документов web/doc/description_en.html или web/doc/description_ru.html, выбор осуществляется автоматически в зависимости от языка, установленого в броузере пользователя.
Если языку броузера не сопоставлен документ, то выбирается первый специфицированный в описании модуля язык (в примере это Английский(English)).
Если вы не зададите языки (аттрибут languages) в определении модуля, то будет отображен документ web/doc/description.html.
Данный модуль весьма полезен для создания информационных портлетов.
Данный тип модуля игнорируется, если целевое приложение не предназначено для работы в портальной среде.

Модуль "только для просмотра"

Модуль, в котором данные можно только простматривать без возможности редактирования, определяется так:

 <module name="CustomerReadOnly">
 <env-var name="XAVA_SEARCH_ACTION" value="CRUD.searchReadOnly"/> <!-- 1 -->
 <model name="Customer"/>
 <controller name="Print"/> <!-- 2 -->
 </module>

Использование CRUD.searchReadOnly (1) в качестве поискового действия запрещает редактирование данных конечным пользователем. Мы оставляем пользователя возможность печати, добавив контроллер Print controller (2) (без указания CRUD или Typical). Соответственно, действия: сохранение (saving), удаление (deleting), и т.д. будут не доступны. Это был пример простейшего модуля, поддерживающего только просмотр данных.

Синтаксис файла application.xml достаточно прост. Дополнительные примеры вы можете почерпнуть OpenXavaTest/xava/application.xml.